CICA 1993 April

home *** CD-ROM | disk | FTP | other *** search

/ CICA 1993 April / CICA MS Windows - April 1993.iso / unzipped / programr / ddeapp / ww0117t.txt

Wrap

Text File | 1991-08-09 | 43KB | 1,109 lines

====================================================================== WW0117: WINDOWS DYNAMIC DATA EXCHANGE (DDE) ====================================================================== Revision Date: 8/91 -------------------------------------------------------------------- | INFORMATION PROVIDED IN THIS DOCUMENT AND ANY SOFTWARE THAT MAY | | ACCOMPANY THIS DOCUMENT (collectively referred to as an | | Application Note) IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY | | KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO | | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A | | PARTICULAR PURPOSE. The user assumes the entire risk as to the | | accuracy and the use of this Application Note. This Application | | Note may be copied and distributed subject to the following | | conditions: 1) All text must be copied without modification and | | all pages must be included; 2) If software is included, all files | | on the disk(s) must be copied without modification [the MS-DOS(R) | | utility DISKCOPY is appropriate for this purpose]; 3) All | | components of this Application Note must be distributed together; | | and 4) This Application Note may not be distributed for profit. | | | | Copyright 1991 Microsoft Corporation. All Rights Reserved. | | Microsoft, MS-DOS, and the Microsoft logo are registered | | trademarks and Windows is a trademark of Microsoft Corporation. | -------------------------------------------------------------------- INTRODUCTION ============ The Windows dynamic data exchange (DDE) protocol is a set of guidelines that allows applications to share data freely. DDE uses either one-time data transfers or ongoing conversations in which applications send updates to one another as new data becomes available. This document introduces Windows DDE through some examples of its use and a detailed example of the operation of the protocol. DDE COMMUNICATIONS CAPABILITIES =============================== It is important to understand that no changes are required to the current or previous shipping versions of Windows to use DDE. Windows allows for very flexible intertask communication. The primary means of communication is the passing of messages. Windows applications receive all of their input in the form of messages. All characters typed at the keyboard, all mouse activity, and all menu selection events are sent to the appropriate Windows applications through messages. In Windows, applications can define private messages that have a unique meaning throughout the system. The DDE protocol defines some new messages for communication between the applications that use DDE. Windows also provides for the sharing of data between applications. The DDE protocol uses shared memory as the means of transferring data from application to application. DDE defines some structures to be used for the contents of the shared memory objects, all of which are discussed below. BASIC RULES =========== DDE is a protocol that allows applications to exchange data on a real- time basis. To perform such an exchange, the two participating applications first have to engage in a DDE conversation. The application that initiates the conversation is known as the client application, and the application responding to the client is known as the server application. A given application can be engaged in several conversations at the same time and can act as the client application in some of them and as the server application in others. Information transferred between applications using DDE can be formatted in a number of ways. Client applications may not support all of the formats available or may prefer certain formats. In general, you do not need to be aware of the different formats, because the client and server applications automatically determine a format and use it to transfer information. A DDE conversation between two applications actually takes place between two windows, one for each of the participating applications. An application opens a window for each conversation it engages in (note that this window is not typically visible). DDE uses the three-level hierarchy -- application, topic, and item -- to uniquely identify a unit of data. Application is the name of the DDE server. Item is a data object that can be passed in a DDE data exchange. Topic is a logical data context. For applications that operate on file-based documents, topics are usually filenames; for other applications, they are other application-specific strings. A syntax example is =Signal|NYSE!IBM which a spreadsheet would read as follows: =Application|Topic!Item This indicates that the cell content is to be the value of the data item "IBM" in the topic "NYSE" of the application "Signal". After a conversation has been started, the client application interacts with the server by issuing transactions. When issuing a transaction, the client asks the server to preform a given action. There are six types of transactions: Request, Advise, Unadvise, Poke, Execute, and Terminate. These are permitted only within an initiated conversation. DDE conversations are one-way: the client application is always the one that issues the transactions. If the server wants to issue a transaction to the client, the server is expected to initiate a new conversation for that purpose. The server becomes the client in this new conversation. (The only exception to the one-way rule is the Terminate transaction, which can be issued by either the client or the server.) DDE CONCEPTS ============ All DDE communication between applications occurs on a channel. The DDE Initiate function is used to open a channel, and the Terminate function is used to close a channel. The application that initiates a channel is called the client, and the other application is called the server. The client controls the channel and requests services from the server. The three functions used by the client on an open DDE channel are Request, Poke, and Execute. Request gets data from the server, Poke sends data to the server, and Execute sends commands to the server. Initiate -------- The Initiate function opens a DDE channel from a client to a server application. The Initiate function has two parameters, the server application name and the topic. The application name is the server program name without the .EXE extension. If the server application is not running, the Initiate function automatically starts it. (Initiate may not automatically start the server from some applications; this is a Microsoft convention.) The topic identifies something in the server application that you plan to access. The topic is often the name of a window in the server application. Initiate returns a channel number. The channel number is subsequently used as a parameter to all other DDE functions to identify the channel in use. You may have more than one channel open by calling the Initiate function several times. An error is returned if the server application is not running and cannot be started, or if the topic is not valid. Request ------- The Request function gets data from the server application. The parameters are the channel number and the item. The channel number is the value returned by Initiate. The item identifies the data to be returned. The server application returns the desired data. An error is returned if the channel number is not valid, the item is not valid, or the server cannot return the data. Poke ---- The Poke function sends data to the server application. The parameters are the channel number, the item, and the data. The channel number is the value returned by Initiate. The item identifies the type of data being sent. The data is the actual data to be sent to the server. An error is returned if the channel number is not valid, the item is not valid, or the server is not able to accept the data. Execute ------- The Execute function sends commands to the server application. The parameters are the channel number and the execute string. The channel number is the value returned by Initiate. The execute string contains one or more commands to be executed by the server. Different server applications support different commands. In general, the commands that can be sent to an application are the commands in that application's menus. An error is returned if the channel number is not valid, or if any errors occur when the server executes the commands in the execute string. Execute does not return data to the client. Terminate --------- The Terminate function closes a DDE channel. The parameter is the channel number of the DDE channel to close. An error is returned if the channel number is not valid. TERMINOLOGY =========== Dynamic Data Exchange (DDE) --------------------------- A Windows protocol that allows two Windows applications to communicate with each other, allowing for the continuous and automatic exchange of data without user intervention. Conversation ------------ Two Windows applications using DDE to exchange data. The conversation is conducted through a channel. DDE client is the application that initiated the conversation; DDE server is the application that responds to the DDE client. Task Identification Number -------------------------- A unique number that identifies a specific copy of an application when several copies are running at the same time. The task ID is appended to the application name to identify the application (for example, Excel4321). Item ---- A reference to a piece of data (such as an integer, a string, a range of cells in a worksheet, a chart, or a bitmap) that can be passed between two applications engaged in a DDE conversation. Topic ----- Information that defines the "subject" of a DDE conversation and represents some unit of data that is meaningful to the DDE server conversation. For most applications that operate on files, this is a filename (for example, SALES.XLS). USES FOR WINDOWS DYNAMIC DATA EXCHANGE ====================================== The uses for DDE mentioned in this section are intended simply as a starting point. There are many possibilities for the use of DDE, and here we can suggest only a few. These are only ideas for the use of DDE; they do not represent a commitment on the part of Microsoft to provide these features in any application. A sample Excel spreadsheet has the following layout: STOCK SHARES PRICE EXTENSION 1 MSFT 3500 78 155000 2 LOTS 500 25 4000 3 TATE 2000 35 7000 4 IBM 1000 148 80000 Without DDE, you could update this spreadsheet using the Clipboard to manually copy numbers from the stock quote application into the Excel spreadsheet. This method requires switching between applications and requires that you pay attention to the price data and undertake the data exchange when desired. With DDE, this system is much more automatic, providing the spreadsheet with the current values for multiple data items without your intervention. DDE allows you to set up a conversation between the server and client applications that keeps the spreadsheet informed of any changes in the value of the stocks that it has asked about. Once this connection is established, the cell value will always reflect the most current data available from the server. No per- transfer intervention on your part is necessary. This facilitates the analysis of real-time data in a timely manner. The usefulness of DDE is not restricted to specialized real-time data acquisition applications. Productivity software in general can benefit significantly from the protocol. For example, suppose you want to prepare a report document monthly using a graphics and text word processor. The report is to include graphics generated in a separate business graphics package. Without DDE, you must perform a manual copy-and-paste process to include each month's new graphs in each month's report document. With DDE, the word processor can establish a permanent link to the charting application so that any changes you make to the charting document are reflected in the word processing document, either automatically or on request. This makes the routine of document preparation much simpler. DDE AND EXCEL ============= HOW TO USE THE EXCEL DDE MACRO COMMANDS ======================================= The examples below all execute another copy of Excel. Any application that supports the DDE protocol could be substituted for Excel. To understand the information presented, you should be familiar with the following (see the "Microsoft Excel Functions and Macros" manual for further reference): Constructing a command macro The EXEC macro command The EXECUTE macro command The INDEX macro command The INITIATE macro command The POKE macro command The REQUEST macro command The TERMINATE macro command Using the INITIATE Command -------------------------- The syntax is as follows: =INITIATE(<app_text>,<topic_text>) <App_text> is the DDE name of the application you are accessing. <Topic_text> is the item in the application you are accessing. The sample macro below executes another copy of Excel and initiates two DDE channels to that copy of Excel. The macro is as follows: A2 =INITIATE("Excel","system") A3 =INITIATE("Excel","Sheet1") A4 =TERMINATE(A2) A5 =TERMINATE(A3) A6 =RETURN() After this macro is executed, no values will have been placed in new locations, but you will have successfully opened and closed two DDE channels. Please note the following: 1. Each time the INITIATE command is executed, a new DDE channel is opened. Each channel is assigned a unique number starting at 0 (zero). The cells containing the two INITIATE commands will contain 0 in the first cell and 1 in the second cell as long as another channel from another INITIATE was not left open. If another channel was left open, the cells will contain the next increment of the channel number. 2. In the above example, DDE channels are initiated with the topics of "system" and "Sheet1". Any Excel sheet name is a valid topic for use in an INITIATE command. The topic of "system" allows you to ask Excel for specific system information. The topics are either "system" or the names of current documents. Using the REQUEST Command ------------------------- The sample macro below executes another copy of Excel and requests a value from the worksheet. The following assumptions are made in this example: 1. A second copy of Excel is being used as the second application for the DDE link. 2. The value being requested is contained in cell A1 of AMORTIZE.XLS. 3. Your EXCEL directory is the current directory. The macro is as follows: A3 Comment: DDE request from Excel A4 =EXEC("excel library\amortize.xls",2) A5 chan=INITIATE("Excel"&A4,"amortize.xls") A6 =REQUEST(chan,"R1C1") A7 =TERMINATE(chan) A8 =RETURN() After this macro is executed, the value in cell A1 of AMORTIZE.XLS can be found on the macro sheet in the cell containing the REQUEST command; in this example, that cell is A6. When you use the REQUEST command to request data from Excel, any referencing made must be in R1C1-type format. If this format is not used, the REQUEST command returns a #REF error. Using the REQUEST Command for System Information ------------------------------------------------ The following example explains how to use the REQUEST command from an Excel macro with the topic of "system". The macro executes another copy of Excel, initiates a DDE channel to that copy of Excel with the topic of "system", and uses the REQUEST command for system information. This example assumes that a second copy of Excel is being used as the second application for the DDE link. The macro is as follows: A3 =INITIATE("Excel","system") A4 =INDEX(REQUEST(A3,"SysItems"),3) A5 =TERMINATE(A3) A6 =RETURN() The request will return an array of the items supported on the topic "system". You can use the INDEX function to access each element of the array of items that is returned. Please note that the system topic "SysItems" returns a list of available "system" items. Any item returned by "SysItems" can be used as a "system" item and, thus, can be used in the REQUEST function. For Excel, the list of available items includes the following: SysItems Topics Status Formats Selection Any of these items is legal for use with the "system" topic in Excel. In the previous example, you could replace your request for "SysItems" with one of the items returned -- for example, "formats": A18 Comment: Getting SysItems from Excel A19 =EXEC("excel",2) A20 chan=INITIATE("Excel"&A19,"System") A21 =REQUEST(chan,"formats") A22 =TERMINATE(chan) A23 =RETURN() To make this macro request the formats from Word for Windows instead, do the following: 1. Delete Cell A19. 2. Change cell A20 to: chan=INITIATE("WinWord","System") You can use the INDEX function to look up values returned by REQUEST. However, if more than one value is to be returned by REQUEST, you can use the FORMULA.ARRAY function in place of INDEX to return all of the values at once. Using the POKE Command ---------------------- This example explains how to use the POKE command from an Excel macro. The sample macro below executes another copy of Excel and places a value into a worksheet. In the following example: 1. A second copy of Excel is being used as the second application for the DDE link. 2. The text to be sent over the DDE channel is contained on the macro sheet in cell A39. 3. The text will be placed into Sheet1 in the second copy of Excel. The macro is as follows: A39 Comment: DDE Poke to another Excel A40 =EXEC("excel",2) A41 chan=INITIATE("Excel"&A40,"Sheet1") A42 =POKE(chan,"R1C1",A39) A43 =TERMINATE(chan) A44 =RETURN() After this macro is executed, the text that is in cell A39 of the macro sheet will have been placed in cell A1 of Sheet1 in the second copy of Excel. When using the POKE command to place a value in another copy of Excel, any references made to the destination sheet must be in R1C1-type format. If this format is not used, the POKE statement returns a #REF error. Using the EXECUTE Command ------------------------- The following macro runs another copy of Excel and makes the other copy of Excel load the file AMORTIZE.XLS from the LIBRARY directory. Note the use of the defined name {q} for quotation marks; this is often a useful technique when sending execute strings that contain quotation marks. A54 Comment: DDE Execute makes another instance of Excel load AMORTIZE.XLS A55 =EXEC("excel",2) A56 chan=INITIATE("Excel"&A55,"Sheet1") A57 q=CHAR(34) A58 =EXECUTE(chan,"[open("&q&"library\amortize.xls"&q&")]") A59 =TERMINATE(chan) A60 =RETURN() Appending a Windows Task ID --------------------------- The EXEC function returns a task ID number for whatever program it starts. This task ID number can be appended to the <app_text> field of the INITIATE function for establishing a DDE channel to the specific instance of the program started by EXEC. However, if the topic of your INITIATE function is already opened and the Ignore Remote Requests box under the Options Workspace menu is selected, you will get the error message Remote data not accessible, start application <APPLICATION.EXE>? where <APPLICATION.EXE> is truncated/expanded to eight characters, as with any DOS filename. If the filename contains fewer than eight characters, then as many of the task ID numbers as will fit to make up eight characters are appended and displayed. Clearing the Ignore Remote Requests option corrects the problem. This can be done by choosing Workspace from the Options menu and manually clearing Ignore Remote Requests, or by using the WORKSPACE function. Excel Format Information ------------------------ Valid Excel 3.0 DDE formats are the following: XLTable BIFF3 SYLK WK1 CSV Text Rich Text Format DIF BITMAP METAFILEPICT Printer_Picture Excel cycles through these formats with each request for data until it receives an acknowledgment from the server. Thus, if a server can supply data only in Text, Excel cycles through all six formats each time it requests data from the server. Speed Issues and DDE -------------------- When Excel receives DDE messages, the messages are posted on the application's message queue along with all other Windows messages. Before Excel processes DDE messages, the messages are taken from the application's queue and stored in a DDE queue. This queue is limited to eight items at a given time. The DDE messages are then processed in tandem with Windows messages on a priority basis (certain Windows messages having greater priority than the DDE messages). This accounts for the speed problems that occur when DDE messages are passed to Excel. Since the DDE queue is fixed at eight items, some items may be lost if the transmission speed of the DDE messages is increased. At this time, the DDE message queue's size cannot be increased. The application sending the DDE data must slow down the rate at which it sends Excel DDE messages for Excel to process them. Sending data to Excel using DDE is fastest if Excel's XLTable format is used. If another format such as Text or CSV is used, Excel must take the time to parse and error check the data instead of accepting it directly. The limit for consecutive messages for the task (application) queue is eight. There is no inherent limit set on the number of DDE links that you can establish within a document. The number is limited only by the amount of available memory. Using the ON.DATA Command in Excel ---------------------------------- Use the ON.DATA command in Excel when you want a particular macro to run any time there is any type of update to a particular worksheet via DDE. The syntax of the formula is: =ON.DATA("<document_text>","<macro_text>") If executed properly, the macro defined by <macro_text> will run every time there is a DDE update to the worksheet specified by <document_text>. When using the ON.DATA command in Excel, you must verify the following: 1. Ignore Remote Requests is not selected in Excel (from the Options menu, choose Workspace). You can ensure that Ignore Remote Requests is not selected by issuing the following macro statement before the ON.DATA command: =WORKSPACE(,,,,,,,false) 2. The argument for <document_text> in the ON.DATA function must refer to a sheet name that contains remote references and only the sheet name, not including cell references. Valid ON.DATA commands look like the following: =ON.DATA("Sheet1.xls","Macro1.xlm!R1C1") =ON.DATA("Sheet1.xls","Macro1.xlm!Macro_name") You must not reference any particular cells. The following would not be valid: =ON.DATA("Sheet1.xls!$A$1","Macro1.xlm!R1C1") =ON.DATA("Sheet1.xls!Area1","Macro1.xlm!Macro_name") Using the Topic "System" to Obtain Word for Windows System Information ---------------------------------------------------------------------- To request system information from Word for Windows in an Excel macro, use the topic "system" when initiating a DDE channel. Once a channel has been opened with the topic "system", Word for Windows recognizes the topics SysItems, Topics, and Formats. Item Effect ---- ------ SysItems Returns a list of all items you can use with the "system" topic Topics Returns a list of currently open documents, including full paths Formats Returns a list of all the Clipboard formats supported by Word for Windows The Excel macro below does the following: 1. Initiates a DDE channel using the topic "system" 2. Uses the topic "Formats" to get the first three formats supported by Word for Windows 3. Places the list into cells A10:A12 The macro is as follows: A1 Comment: DDE_Example A2 =INITIATE("Winword","system") A3 =INDEX(REQUEST(A2,"Formats"),1) A4 =FORMULA(A3,A10) A5 =INDEX(REQUEST(A2,"Formats"),2) A6 =FORMULA(A5,A11) A7 =INDEX(REQUEST(A2,"Formats"),3) A8 =FORMULA(A7,A12) A9 =RETURN() A10 Rich Text Format A11 TEXT A12 METAFILEPICT DDE AND WORD FOR WINDOWS ======================== Word for Windows uses two different types of DDE commands: WordBasic commands, which are designed for complex or custom DDE conversations, and DDE fields, intended for simple links updating information from supporting documents, either manually or automatically. MACRO COMMANDS ============== When using DDE with Word for Windows as the client you should use the Windows Dynamic Link Library GetModuleHandle to determine if your server application is loaded or not (see page 25 in the "Microsoft Word for Windows Technical Reference). If it is not loaded, issue a Shell command to load it. You may also specify the document that will be loaded. In the example below, a user defined function IsAppLoaded is declared (see page 19 in the "Microsoft Word for Windows Technical Reference;" or pages 70-71 of the "Microsoft Word for Windows and OS/2 Technical Reference"). IsAppLoaded is a library function in the Windows kernel listed as GetModuleHandle. IsAppLoaded takes a single string parameter that is the name of the application you are checking on -- in this case, Server. If Server is already in memory, IsAppLoaded is true, returning a non-zero value. In the following routine, the text between <> should appear as one line without the <> symbol: <Declare Function IsAppLoaded Lib "kernel" (name$) As Integer Alias "GetModuleHandle"> Sub Main If IsAppLoaded("Server") = 0 then Shell "server" chan = DDEInitiate("server", "stockinfo") DDETerminate chan End Sub Note: The term "Server" is used here in a general sense. It could be replaced with any Windows application's DDE name. If Server is not in memory, the Shell statement will load it. The second parameter indicates Server should be loaded as an icon. It is also possible to specify a filename to be loaded when an application is Shelled. The syntax is Shell "<servername> <path\filename>", 2 where <servername> is the name of the network server you want to access, and path\filename> is the path to and name of the application to start. By using the IsAppLoaded function to determine if the server application needs to be loaded or not, you can avoid the message "Remote data (<filename>) not accessible: Start application <appname> ? Y/N ? ". This reduces the need for operator intervention. We recommend that you use the following code syntax when establishing DDE communication, replacing the references to Excel and ANNUAL.XLS with the appropriate server name and topic. In the following routine, the text between <> should appear as one line without the <> symbol: <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias "GetModuleHandle"> Sub Main If IsAppLoaded("excel") = 0 Then Shell "excel c:\annual.xls" chan1 = DDEInitiate("excel", "annual.xls") DDETerminateAll End Sub Each time a DDEInitiate statement is executed, a new instance of the server will be loaded. For applications permitting only a single instance to be loaded this method will generate errors. To overcome this problem, use the topic "system" when establishing the DDE channel. This will establish the channel to the application's main window instead of to a specific file (<topic>). Then use the DDEExecute commands to open and close individual files as needed. In the following routine, the text between <> should appear as one line without the <> symbol: <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias "GetModuleHandle"> Sub Main If IsAppLoaded("server") = 0 Then Shell "server" chan1 = DDEInitiate("server", "system") DDETerminateAll End Sub Use of the topic "system" with Word for Windows allows access to three special items -- SysItems, Topics, and Formats. Item Effect ---- ------ SysItems Returns a list of all items you can use with the "system" topic Topics Returns a list of currently open documents, including full paths Formats Returns a list of all the Clipboard formats supported by Word for Windows Word returns these values in CF_Text format (ASCII text). Items in a list are separated by tabs. COMMAND SYNTAX ============== DDEInitiate ----------- When Word is the client application, DDEInitiate is used to attempt to start a conversation with another application that will be the server. If the command is successful, a channel number, which will be greater than 1, is returned. The number of channels that can be opened is limited by memory. Syntax: DDEInitiate(<App$>, <Topic$>) where <App$> is a text string indicating the DDE name of the application that will be the server. <Topic$> will normally be the name of a document or file, but this is application specific. When the DDEInitiate command is executed, a DDE channel is opened to the specified application and file. The DDE channel numbers begin with 1 and increment as each channel is opened. When a channel is terminated, that channel number will be reused for the next DDEInitiate. In normal usage, the return value -- the channel number -- is assigned to a variable. Referencing the variable is preferable to using the actual channel number. For example: chan = DDEInitiate ("excel","budget.xls") If Excel and BUDGET.XLS are found and started, the returned channel number is assigned to the variable chan. Then, you would use chan when referring to this channel. If the <app$> or <topic$> is not found, an error is generated. Using the WordBasic On Error statements, you can trap these errors and institute error routines to allow the user to respecify the <app$> or <topic$> so your macro can continue. In the example below, the application DDE name for Excel is assigned to the string variable App1$, and the name of the worksheet wanted, BUDGET.XLS, to Topic1$. Then, the DDEInitiate command is issued, the variables App1$ and Topic1$ are used. In the following routine, the text between <> should appear as one line without the <> symbol: <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias "GetModuleHandle"> Sub Main If IsAppLoaded("Excel") = 0 Then Shell "excel" App1$ = "excel" Topic1$ = "budget.xls" chan = DDEInitiate (App1$, Topic1$) End Sub DDE Terminate ------------- Syntax: DDETerminate <ChanNum> DDETerminate closes a DDE channel after all communication is completed. It is useful when multiple conversations are going on and you want to end one while maintaining the others. By assigning a variable to the returned channel number, you can selectively end individual DDE conversations. In the example below, DDE channel chan2 is opened and selectively closed, and another server is opened while maintaining the DDE channel chan1. Finally, both channels are closed by issuing individual DDETerminate statements. In the following routine, the text between <> should appear as one line without the <> symbol: <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias "GetModuleHandle"> Sub Main If IsAppLoaded("excel") = 0 Then Shell "excel" chan1 = DDEInitiate ("excel", "budget.xls") If IsAppLoaded("server") = 0 Then Shell "server" chan2 = DDEInitiate ("server", "stockinfo") DDETerminate chan2 If IsAppLoaded("SB4W") = 0 Then Shell "SB4W" chan2 = DDEInitiate ("SB4W", "system") DDETerminate chan2 DDETerminate chan1 End Sub DDETerminateAll --------------- Syntax: DDETerminateAll DDETerminateAll terminates all DDE channels in which Word for Windows is a client. It can be used as a general cleanup to ensure that all channels have been closed without you having to know which channels are open. In the example below, two independent DDE conversations, chan1 and chan2, are started, and DDETerminateAll closes both sessions. In the following routine, the text between <> should appear as one line without the <> symbol: <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias "GetModuleHandle"> Sub Main If IsAppLoaded("excel") = 0 Then Shell "excel" chan1 = DDEInitiate ("excel", "budget.xls") If IsAppLoaded("server") = 0 Then Shell "server" chan2 = DDEInitiate ("server", "stockinfo") DDETerminateAll End Sub DDERequest$ ----------- Syntax: data$ = DDERequest$ (<ChanNum>, <Item$>) DDERequest$ requests specific information from the server on <Item$> using the DDE channel designated. The channel must have previously been opened using DDEInitiate. Because data is returned in CF_TEXT format, it can only be assigned to a string variable. If a numeric value is needed, use the Val statement to convert the text string to a numeric. Pictures or text in rich-text format cannot be transferred using DDERequest$. If DDERequest$ is unsuccessful, a null string ("") is returned. In the example below, a DDE channel to Excel and the worksheet BUGDET.XLS is opened and assigned to chan. A request for information on the item IBM is sent. If successful, the current value of the defined name balance is printed on the status line; otherwise, a null string is returned, and nothing is displayed on the status line. In the following routine, the text between <> should appear as one line without the <> symbol: <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias "GetModuleHandle"> Sub Main If IsAppLoaded("server") = 0 Then Shell "server" chan = DDEInitiate ("server", "stockinfo") data$ = DDERequest$ (chan, "ibm") Print data$ DDETerminate chan End Sub In the example below, a channel is opened and information from the <item$> balance is requested. If the reference "balance" is not defined in the document BUDGET.XLS, a null string is received. In the following routine, the text between <> should appear as one line without the <> symbol: <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias "GetModuleHandle"> Sub Main chan = DDEInitiate ("excel", "budget.xls") data$ = DDERequest$ (chan, "balance") Print data$ DDETerminate chan End Sub DDEPoke ------- Syntax: DDEPoke <ChanNum>, <Item$>, <Data$> DDEPoke is used by a client to send information to the server. The string variable <Data$> is sent to the location, <Item$>, using <ChanNum>. If the <Item$> does not exist, a WordBasic error is generated. In the example below, after establishing a DDE channel with Server, a request is made for the <Item$> TOTAL, which is a named reference in BUDGET.XLS. If the numeric value of the string returned is 0, the amount $100.00 is POKEd into the cell referenced by TOTAL. If the named reference TOTAL does not exist in BUDGET.XLS, a WordBasic error 503, "Process failed in other application," is returned. In the following routine, the text between <> should appear as one line without the <> symbol: <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias "GetModuleHandle"> Sub Main If IsAppLoaded("Excel") = 0 Then Shell "excel" chan = DDEInitiate ("excel", "c:\accts\budget.xls") data$ = DDERequest$ (chan, "total") If val(data$) = 0 then DDEPoke chan, "total", "$100.00" DDETerminate chan End Sub DDEExecute ---------- Syntax: DDEExecute <ChanNum>, <ExecuteString$> DDEExecute is used by a client to execute a command, function, or macro in the server. The string variable <ExecuteString$> is the server's command, function, or macro. If the <ExecuteString$> does not exist, a WordBasic error is generated. When executed, the macro below checks to see if Excel is already running. If it is not, the macro starts Excel. If you don't know what sheet(s) is currently open when Excel is loaded, use "system" as the second parameter of the DDEInitiate command. You can then issue an Excel OPEN command using DDEExecute to open a specific file. In the following routine, the text between <> should appear as one line without the <> symbol: <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias "GetModuleHandle"> Sub MAIN If IsAppLoaded ("EXCEL") = 0 Then Shell "EXCEL.EXE" ExecuteString$ = "=B1{enter}" ChanNum = DDEInitiate("EXCEL", "C:\WINDOWS\SHEET1.XLS") DDEExecute ChanNum, "[App.Restore()][Formula.Goto( " + Chr$(34) + "test" + Chr$(34) + ")]" DDEExecute ChanNum, ExecuteString$ DDEExecute ChanNum, "[App.Minimize()]" DDETerminate ChanNum End Sub The Formula.Goto statement in the above DDEExecute statement is the equivalent of the following Excel macro statement: =FORMULA.GOTO("test") FIELD CODES -- DDEAUTO AND DDE ============================== DDE field codes are best used when you are working with a document containing information from supporting documents that changes periodically. To maintain the most current information in the dependent document, use a DDE field code to link to the supporting document. DDEAuto will handle the updating automatically for you -- always using the most current version of the source document. The DDE field code allows you to manually update the information by pressing F9. You can create these fields three different ways: 1. Manually enter the field brackets by pressing CTRL+F9. Type the field type and topic-item information. 2. From the Insert menu, choose Fields and select the DDE field types in the Insert Field Type box. 3. From the Edit menu, choose Copy and then Paste Link, selecting the Auto Update option if desired. Syntax: {DDE [<path>]<appname> <filename> [<reference>]} {DDEAuto [<path>]<appname> <filename> [<reference>]} Note: The braces -- { } -- are not typed; they are inserted when you choose Field from the Insert menu (or press CTRL+F9). If a path is specified, it must include double backslashes ( \\ ). The <reference> is optional. The following field statement example is an automatic update link to the server BUDGET.XLS file for cells R1C1:R4C4. Changing the field name from DDEAUTO to DDE will change the updating linkage from automatic to manual. {DDEAuto c:\\apps\\server\\budget.xls R1C1:R4C4} INCLUDING EXCEL CHARTS IN WORD FOR WINDOWS DOCUMENTS ==================================================== The easiest way to perform a DDE link from an Excel chart to Word for Windows is to do the following: 1. In Excel, choose Select Chart from the Chart menu. 2. From the Edit menu, choose Copy. 3. Switch to Word for Windows (by pressing ALT+TAB). 4. Position the insertion point at the point where you want to place the chart. 5. From the Edit menu, choose Paste Link. 6. In the Paste Link dialog box, select the Auto Update option if you want Word for Windows to automatically update the chart whenever it changes in Excel. If Auto Update is not selected, you must select the chart and recalculate it (by pressing F9) for new charts to appear. When the above procedure is followed, Word inserts one of the following fields into the document: Auto Update Option Field Inserted in Document ------------------ -------------------------- Selected {ddeauto Excel Chart1 "" \* mergeformat} Not selected {dde Excel Chart1 "" \* mergeformat} Once the chart is placed in the Word document, the chart can be scaled or cropped. DISPLAYING DDE LINKED PICTURES ============================== When you use DDE to link a chart in Excel to a document in Word for Windows using the Auto Update feature, the charts in some cases will not be identical. Because Word for Windows wants the format that will look the best when printed, it asks Excel for a different format than is displayed by Excel. Therefore, the images will not always match. For example, color will not be retained in a chart from Excel that is linked to Word for Windows if the printer driver being used does not support color. The WIN.INI parameter AskforPrinterPicture= can be used to determine how Microsoft Word for Windows will display DDE linked pictures. This parameter affects only DDE links and should be entered in the [Microsoft Word] section of the WIN.INI file. To modify the WIN.INI, use a text editor such as Notepad, or use Word for Windows and save the WIN.INI as Text Only. The following example allows Word for Windows to display a DDE paste- linked picture as it would display when printed: [Microsoft Word] AskforPrinterPicture=1 If a color printer is installed, then the picture displays in color. Otherwise, it displays in black and white. The following example allows Word for Windows to display a DDE paste- linked picture in color, regardless of the installed printer: [Microsoft Word] AskforPrinterPicture=0 DDE AND Q+E FOR MICROSOFT EXCEL =============================== Q+E can be used with Excel, Word for Windows, or any other application that supports DDE. For information on using DDE with Q+E, see the "Q+E for Microsoft Excel User's Guide."